ATSUPositionToOffset

Obtains the edge offset(s) that correspond to the glyph nearest a mouse-down event.

OSStatus ATSUPositionToOffset (
                     ATSUTextLayout iTextLayout,
                     ATSUTextMeasurement iLocationX,
                     ATSUTextMeasurement iLocationY,
                     UniCharArrayOffset *ioPrimaryOffset,
                     Boolean *oIsLeading,
                     UniCharArrayOffset *oSecondaryOffset);
iTextLayout
A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iLocationX
A value of type ATSUTextMeasurement. Pass the x-coordinate of the origin of the line (in the current graphics port) where the mouse-down event occurred. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want the location of the mouse-down event relative to the current pen location in the current graphics port.

iLocationY
A value of type ATSUTextMeasurement. Pass the y-coordinate of the origin of the line (in the current graphics port) where the mouse-down event occurred. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want the location of the mouse-down event relative to the current pen location in the current graphics port.

ioPrimaryOffset
A pointer to a value of type UniCharArrayOffset. Before calling ATSUPositionToOffset, pass a pointer to the edge offset of the beginning of the line containing the character nearest the mouse-down event. If the line direction is right-to-left, pass the lowest edge offset. On return, the edge offset that corresponds to the closest edge of the glyph beneath the hit point on the screen. You cannot pass NULL for this parameter.

oIsLeading
A pointer to a Boolean value. On return, the value indicates whether the offset passed back in the ioPrimaryOffset parameter is leading or trailing. If this value is true, the offset is leading (more closely associated with the following character in the backing-store memory). If this value is false, the offset is trailing (more closely associated with the previous character in the backing-store memory). This value indicates the line direction at the location of the mouse-down event.

oSecondaryOffset
A pointer to a value of type UniCharArrayOffset. On return, the edge offset that corresponds to the furthest edge of the glyph beneath the hit point on the screen. This value is the same as passed back in ioPrimaryOffset unless the mouse-down event occurs on a line direction boundary.

function result
A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt). The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.
DISCUSSION
The ATSUPositionToOffset function obtains the edge offset(s) that correspond to the glyph nearest a mouse-down event. If the mouse-down event occurs at a line direction boundary, a second offset is passed back in the oSecondaryOffset parameter representing the offset that corresponds to the furthest edge of the glyph beneath the hit point on the screen. A line direction boundary can occur on the trailing edges of two glyphs, the leading edges of two glyphs, or at the beginning or end of a text segment. The value passed back in the oIsLeading parameter indicates the line direction of the text at the location of the mouse-down event.

The user expects that pressing the mouse button correlates to particular actions in an application. You can use the offset(s) passed back in ATSUPositionToOffset for providing feedback or performing any actions in response to the user.

For example, if the user presses the mouse button in text, your application should pass the resulting edge offset to ATSUOffsetToPosition to determine the caret position(s) corresponding to this offset. If the user presses the mouse button while the cursor is on a glyph and drags the cursor across a range of text, then releases the mouse, your application might want to respond by highlighting the text between the mouse-down and mouse-up events. To do this, you would pass the edge offset (s) passed back from ATSUPositionToOffset that correspond to the mouse-up and mouse-down event positions to the ATSUHighlightText function.

If the user then presses the mouse button outside the highlighted area, your application should pass the same edge offsets to the ATSUUnhighlightText function. If the user double clicks (word selection) or triple clicks (paragraph selection), You can pass the resulting primary edge offset to ATSUOffsetToPosition to determine the caret position(s) corresponding to this offset.

ATSUI does not keep actual line positions. As a result, the coordinates passed in the iLocationX and iLocationY parameters are relative to the position in the current graphics port of the origin of the line in which the mouse-down occurred. The passed back edge offset(s) are thus offsets from the beginning of the line in which the hit occurred, not from the beginning of the text layout object's buffer.

To transform the hit point's position, you must first call the GlobalToLocal function, described in "Basic QuickDraw" in Inside Macintosh: Imaging with QuickDraw , to translate the global coordinates passed back in the where field of the event record to local coordinates. For more information about responding to mouse-down events, see the "The Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials . You then subtract the hit point (in local coordinates) from the position of the line's origin in the current graphics port.

For example, if you have a mouse-down event whose position in local coordinates is (75,50), you would subtract this value from the position of the origin of the line in the current graphics port. If the position of the origin of the line in the current graphics port is (50,50), then the relative position of the hit that you would pass in the iLocationX and iLocationY parameters would be (25,0).

ATSUPositionToOffset passes back a Boolean value in the oIsLeading parameter to tell you the text direction of the primary edge offset. This directionality is determined by the Unicode directionality of the original character in backing-store memory. If it passes back true, the primary edge offset is more closely associated with the following character in the backing-store memory. If it passes back false, the primary offset is more closely associated with the previous character in the backing-store memory.

The following summarizes the possible outcomes of calling ATSUPositionToOffset:

SPECIAL CONSIDERATIONS
ATSUPositionToOffset may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES
Available beginning with ATSUI 1.0.

© 2000 Apple Computer, Inc. – (Last Updated 25 Jan 00)